# Sui Programmable Transaction Basics

This example starts by constructing a transaction to send SUI. To construct transactions, import the
`Transaction` class and construct it:

```tsx
import { Transaction } from '@mysten/sui/transactions';

const tx = new Transaction();
```

You can then add transactions to the transaction .

```tsx
// create a new coin with balance 100, based on the coins used as gas payment
// you can define any balance here
const [coin] = tx.splitCoins(tx.gas, [100]);

// transfer the split coin to a specific address
tx.transferObjects([coin], '0xSomeSuiAddress');
```

You can attach multiple transactions of the same type to a transaction, as well. For example, to get
a list of transfers and iterate over them to transfer coins to each of them:

```tsx
interface Transfer {
	to: string;
	amount: number;
}

// procure a list of some Sui transfers to make
const transfers: Transfer[] = getTransfers();

const tx = new Transaction();

// first, split the gas coin into multiple coins
const coins = tx.splitCoins(
	tx.gas,
	transfers.map((transfer) => transfer.amount),
);

// next, create a transfer transaction for each coin
transfers.forEach((transfer, index) => {
	tx.transferObjects([coins[index]], transfer.to);
});
```

After you have the transaction defined, you can directly execute it with a signer using
`signAndExecuteTransaction`.

```tsx
client.signAndExecuteTransaction({ signer: keypair, transaction: tx });
```

## Observing the results of a transaction

When you use `client.signAndExecuteTransaction` or `client.executeTransactionBlock`, the transaction
will be finalized on the blockchain before the function resolves, but the effects of the transaction
may not be immediately observable.

There are 2 ways to observe the results of a transaction. Methods like
`client.signAndExecuteTransaction` accept an `options` object with options like `showObjectChanges`
and `showBalanceChanges` (see
[the SuiClient docs for more details](/typescript/sui-client#arguments)). These options will cause
the request to contain additional details about the effects of the transaction that can be
immediately displayed to the user, or used for further processing in your application.

The other way effects of transactions can be observed is by querying other RPC methods like
`client.getBalances` that return objects or balances owned by a specific address. These RPC calls
depend on the RPC node having indexed the effects of the transaction, which may not have happened
immediately after a transaction has been executed. To ensure that effects of a transaction are
represented in future RPC calls, you can use the `waitForTransaction` method on the client:

```typescript
const result = await client.signAndExecuteTransaction({ signer: keypair, transaction: tx });
await client.waitForTransaction({ digest: result.digest });
```

Once `waitForTransaction` resolves, any future RPC calls will be guaranteed to reflect the effects
of the transaction.

## Transactions

Programmable Transactions have two key concepts: inputs and transactions.

Transactions are steps of execution in the transaction. Each Transaction in a Transaction takes a
set of inputs, and produces results. The inputs for a transaction depend on the kind of transaction.
Sui supports following transactions:

- `tx.splitCoins(coin, amounts)` - Creates new coins with the defined amounts, split from the
  provided coin. Returns the coins so that it can be used in subsequent transactions.
  - Example: `tx.splitCoins(tx.gas, [100, 200])`
- `tx.mergeCoins(destinationCoin, sourceCoins)` - Merges the sourceCoins into the destinationCoin.
  - Example: `tx.mergeCoins(tx.object(coin1), [tx.object(coin2), tx.object(coin3)])`
- `tx.transferObjects(objects, address)` - Transfers a list of objects to the specified address.
  - Example: `tx.transferObjects([tx.object(thing1), tx.object(thing2)], myAddress)`
- `tx.moveCall({ target, arguments, typeArguments  })` - Executes a Move call. Returns whatever the
  Sui Move call returns.
  - Example:
    `tx.moveCall({ target: '0x2::devnet_nft::mint', arguments: [tx.pure.string(name), tx.pure.string(description), tx.pure.string(image)] })`
- `tx.makeMoveVec({ type, elements })` - Constructs a vector of objects that can be passed into a
  `moveCall`. This is required as there’s no way to define a vector as an input.
  - Example: `tx.makeMoveVec({ elements: [tx.object(id1), tx.object(id2)] })`
- `tx.publish(modules, dependencies)` - Publishes a Move package. Returns the upgrade capability
  object.

## Passing inputs to a transaction

Transaction inputs can be provided in a number of different ways, depending on the transaction, and
the type of value being provided.

#### JavaScript values

For specific transaction arguments (`amounts` in `splitCoins`, and `address` in `transferObjects`)
the expected type is known ahead of time, and you can directly pass raw javascript values when
calling the transaction method. appropriate Move type automatically.

```ts
// the amount to split off the gas coin is provided as a pure javascript number
const [coin] = tx.splitCoins(tx.gas, [100]);
// the address for the transfer is provided as a pure javascript string
tx.transferObjects([coin], '0xSomeSuiAddress');
```

#### Pure values

When providing inputs that are not on chain objects, the values must be serialized as

[BCS](https://sdk.mystenlabs.com/bcs), which can be done using `tx.pure` eg,
`tx.pure.address(address)` or `tx.pure(bcs.vector(bcs.U8).serialize(bytes))`.

`tx.pure` can be called as a function that accepts a SerializedBcs object, or as a namespace that
contains functions for each of the supported types.

```ts
const [coin] = tx.splitCoins(tx.gas, [tx.pure.u64(100)]);
const [coin] = tx.splitCoins(tx.gas, [tx.pure(bcs.U64.serialize(100))]);
tx.transferObjects([coin], tx.pure.address('0xSomeSuiAddress'));
tx.transferObjects([coin], tx.pure(bcs.Address.serialize('0xSomeSuiAddress')));
```

To pass `vector` or `option` types, you you can pass use the corresponding methods on `tx.pure`, use
tx.pure as a function with a type argument, or serialize the value before passing it to tx.pure
using the bcs sdk:

```ts
import { bcs } from '@mysten/sui/bcs';

tx.moveCall({
	target: '0x2::foo::bar',
	arguments: [
		// using vector and option methods
		tx.pure.vector('u8', [1, 2, 3]),
		tx.pure.option('u8', 1),
		tx.pure.option('u8', null),

		// Using pure with type arguments
		tx.pure('vector<u8>', [1, 2, 3]),
		tx.pure('option<u8>', 1),
		tx.pure('option<u8>', null),
		tx.pure('vector<option<u8>>', [1, null, 2]),

		// Using bcs.serialize
		tx.pure(bcs.vector(bcs.U8).serialize([1, 2, 3])),
		tx.pure(bcs.option(bcs.U8).serialize(1)),
		tx.pure(bcs.option(bcs.U8).serialize(null)),
		tx.pure(bcs.vector(bcs.option(bcs.U8)).serialize([1, null, 2])),
	],
});
```

#### Object references

To use an on chain object as a transaction input, you must pass a reference to that object. This can
be done by calling `tx.object` with the object id. Transaction arguments that only accept objects
(like `objects` in `transferObjects`) will automatically treat any provided strings as objects ids.
For methods like `moveCall` that accept both objects and other types, you must explicitly call
`tx.object` to convert the id to an object reference.

```ts
// Object IDs can be passed to some methods like (transferObjects) directly
tx.transferObjects(['0xSomeObject'], 'OxSomeAddress');
// tx.object can be used anywhere an object is accepted
tx.transferObjects([tx.object('0xSomeObject')], 'OxSomeAddress');

tx.moveCall({
	target: '0x2::nft::mint',
	// object IDs must be wrapped in moveCall arguments
	arguments: [tx.object('0xSomeObject')],
});

// tx.object automaically converts the object ID to receiving transaction arguments if the moveCall expects it
tx.moveCall({
	target: '0xSomeAddress::example::receive_object',
	// 0xSomeAddress::example::receive_object expects a receiving argument and has a Move definition that looks like this:
	// public fun receive_object<T: key>(parent_object: &mut ParentObjectType, receiving_object: Receiving<ChildObjectType>) { ... }
	arguments: [tx.object('0xParentObjectID'), tx.object('0xReceivingObjectID')],
});
```

When building a transaction, Sui expects all objects to be fully resolved, including the object
version. The SDK automatically looks up the current version of objects for any provided object
reference when building a transaction. If the object reference is used as a receiving argument to a
`moveCall`, the object reference is automatically converted to a receiving transaction argument.
This greatly simplifies building transactions, but requires additional RPC calls. You can optimize
this process by providing a fully resolved object reference instead:

```ts
// for owned or immutable objects
tx.object(Inputs.ObjectRef({ digest, objectId, version }));

// for shared objects
tx.object(Inputs.SharedObjectRef({ objectId, initialSharedVersion, mutable }));

// for receiving objects
tx.object(Inputs.ReceivingRef({ digest, objectId, version }));
```

#### Transaction results

You can also use the result of a transaction as an argument in a subsequent transactions. Each
transaction method on the transaction builder returns a reference to the transaction result.

```tsx
// split a coin object off of the gas object
const [coin] = tx.splitCoins(tx.gas, [100]);
// transfer the resulting coin object
tx.transferObjects([coin], address);
```

When a transaction returns multiple results, you can access the result at a specific index either
using destructuring, or array indexes.

```tsx
// destructuring (preferred, as it gives you logical local names)
const [nft1, nft2] = tx.moveCall({ target: '0x2::nft::mint_many' });
tx.transferObjects([nft1, nft2], address);

// array indexes
const mintMany = tx.moveCall({ target: '0x2::nft::mint_many' });
tx.transferObjects([mintMany[0], mintMany[1]], address);
```

## Get transaction bytes

If you need the transaction bytes, instead of signing or executing the transaction, you can use the
`build` method on the transaction builder itself.

**Important:** You might need to explicitly call `setSender()` on the transaction to ensure that the
`sender` field is populated. This is normally done by the signer before signing the transaction, but
will not be done automatically if you’re building the transaction bytes yourself.

```tsx
const tx = new Transaction();

// ... add some transactions...

await tx.build({ client });
```

In most cases, building requires your SuiClient to fully resolve input values.

If you have transaction bytes, you can also convert them back into a `Transaction` class:

```tsx
const bytes = getTransactionBytesFromSomewhere();
const tx = Transaction.from(bytes);
```
